|
The CommonUserInterface,
or CUI, provides a Web interface to the EBR information network.
The CUI is available as a Java Servlet web
application. It is available to download and install locally for EbrPartners
that wish to offer the service to a set of customers.
- a network / systems administrator to install the application.
Familiarity with the installation of Java™ Servlets would be
highly beneficial.
- if modifications to the CUI are to be made, a developer with
XML/XSLT/HTML skills is desirable
- a computer system connected to the Internet (with specific
ports open to the EBR network) capable of running Java™ 1.4.X
- a valid and operational EBR Core Software LD/ND Node. The CUI
communicates with the EBR network entirely by sending EBR MIME
messages via the LD/ND Node.
- a Java™ Servlet container that meets the Sun Java™ Servlet
Specification level 2.3. A comprehensive list of leading Java™
Servlet containers can be found here
- a relational database management system and corresponding
Java™ JDBC driver
- NOTE: This section assumes you are using Apache
Tomcat v4.1.18. If you are using a different Java™ Servlet container
then the installation may differ.
* Download and install the Java™ Servlet container. Information
on installing the Apache Tomcat container can be found at http://jakarta.apache.org/tomcat/tomcat-4.1-doc/index.html
- Download the CUI distribution from the AdminSite.
It is packaged as a Zip file and will have a filename of the form
cui_VX_XXX.zip, where the X's are the current version.
- Extract the CUI distribution into a convenient location, such
that it can be accessed by your servlet container. For the
purposes of the remainder of this document, this folder shall be
referred to as
$CUI_HOME. If successfully extracted
the $CUI_HOME directory should contain the following:
| cui.war |
The CUI web application |
| config |
Configuration files |
| docs |
Associated documentation |
| logs |
Log files |
After InstallingTheCui
the next step is to ensure that the CUI application is correctly
configured. Please follow the listed steps:
The distribution depends on a configuration file which can
be found at $CUI_HOME/config/cuiconfig.xml. This is
used to configure how the key aspects of the system function, from
the available languages to how to display prices to the end user.
Edit the configuration file
($CUI_HOME/config/cuiconfig.xml) to suit your
installation requirements. The template xml document supplied should
contain enough information to guide you through the process. If you
need to start again, a sample config file can be found at
$CUI_HOME/docs/samples/cuiconfig.xml.
For
the CUI to run correctly it must be registered with your servlet
container. Please refer to your vendors documentation on how to do
this. We will continue to focus on Apache Tomcat.
With Apache Tomcat, we need to edit the servers configuration
file $CATALINA_HOME/conf/server.xml, where
$CATALINA_HOME refers to the installation directory of Apache
Tomcat. We must then add a new 'Context' to the localhost Host
element. The path attribute specifies the url of the cui relative to
the server. The docBase represents the absolute path to the WAR file
for the CUI.
You have now created the CUI webapp, although it is not ready to
startup yet!
The
CUI webapp also needs to know where the CUI config file resides
(this is the XML file that we edited earlier). We need to register
an Environment Entry for the CUI Context with the name
cuiConfigFile, the value of which should be the absolute path to
your CUI configuration file.
Apache Tomcat enables us to register an Environment Entry using
the Environment tag, so we add this to the Context for the CUI that
we created in the previous section. So we now have:
<Host name="localhost" ...>
...
...
...
<Context path="/MyCUIInstallation" docBase="$CUI_HOME/cui.war"/>
<Environment name="cuiConfigFile" type="java.lang.String"
value="file://$CUI_HOME/config/cuiconfig.xml" override="false"/>
...
...
...
</Context>
</Host> We are very close now!
From the CuiMilestoneSix
release the CUI and CAI require an additional
Environment entry to be present in the
Context section of the server.xml file
named EbrAccessControllerClass.
<Environment name="EbrAccessControllerClass" type="java.lang.String" value="com.orctel.ebr.network.EbrDefaultAccessController" override="false"/> This entry points to the class that will be in charge of the
CUI/CAI interaction with EBR orders, users and accounts. By default
this should be set to to the value shown above. It is only to be
altered by advanced countries who want to override the default
behaviour, perhaps to hook up their own account system
implementation via the AbstractClasses.
 - WARNING: - this entry
must appear. If it is not present the
CUI/CAI will not start.
- WARNING: Make sure the CUI and CAI use
the same database resources
The CUI/CAI webapp requires a database in order to operate,
however all you as the installer need to do is provide a resource
reference. Your servlet container should have detailed information
on how to create this.
Apache Tomcat uses a Resource tag to register the object with a
name and type so that the server knows how to handle a request for
the object. The name must be set to jdbc/ebrusr, the
type may be any class implementing the
javax.sql.DataSource interface.
The ResourceParams tag is used to configure parameters required
for the associated Resource (NOTE: the corresponding name
attributes). Here we can configure connection information for the DataSource,
and also configure additional information such as the maximum number
of connections allowed.
<Host name="localhost" ...>
...
...
...
<Context path="/MyCUIInstallation" docBase="$CUI_HOME/cui.war"/>
<Environment name="cuiConfigFile" type="java.lang.String" value="file://$CUI_HOME/config/cuiconfig.xml"
override="false"/>
<!-- This registers a local database for usage by the CUI.
The resource name must be set to jdbc/ebrusr and
sufficient information must be given to enable the
creation of a connection to the database.
-->
<Resource name="jdbc/ebrusr" auth="Container" type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/ebrusr">
<parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<parameter>
<name>username</name>
<value>YOUR.DS.USERNAME</value>
</parameter>
<parameter>
<name>password</name>
<value>YOUR.DS.PASSWORD</value>
</parameter>
<!-- Class name for mm.mysql JDBC driver -->
<parameter>
<name>driverClassName</name>
<value>YOUR.DS.JDBCDRIVER</value>
</parameter>
<!-- The JDBC connection url for connecting to your MySQL dB.
The autoReconnect=true argument to the url makes sure that the
mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
connection. mysqld by default closes idle connections after 8 hours.
-->
<parameter>
<name>url</name>
<value>YOUR.DS.URL</value>
</parameter>
</ResourceParams>
</Context>
</Host> - Please ensure that the driver registered for the
datasource can be found on the CLASSPATH for the webapp
(in Apache Tomcat this should be placed into
$CATALINA_HOME/common/lib. There are no drivers
included within the CUI/CAI distribution.
- NOTE: Don't forget to include the 'url' making
sure you add the name of the database you intend to install the CUI
tables into.
Within the CUI distribution you can find a file containing
the SQL statements required to create the ebrusr
database, this can be found at
$CUI_HOME/docs/create_tables.sql. The file contains
simple ANSI SQL statements to ensure portability, we advise that
this file is edited in order to tune the tables for your database
system performance.
Hint: The create_tables.sql
attempts to create a database with the name ebrusr. If
this clashes with any of your pre-installed applications, then you
must change the create database name and update all references to
this name in the create_tables.sql file. Don't forget
to ensure the DataSource
parameter url is updated with the new database name (in
your servers configuration file).
Hint: We advise that you change the default
users (or at least passwords) that are inserted into the database
when you execute the create_tables.sql. This is
essential for the CAI user.
- WARNING: Do not edit the database,
table or column names. If you change any column types, please ensure
they will map to the same java.sql.* and
javax.sql.* classes.
Most database vendors enable a command line creation of tables
using a file containing SQL statements. Please refer to your
database documentation for details on how to achieve this. This is
an example using MySQL:
mysql -udbusername -p < create_tables.sql
You are now ready to test your CUI installation.
Restart the container, any errors will result in a Servlet
exception being thrown making th CUI webapp unavailable. Check both
the server log and CUI log ($CUI_HOME/logs/cui.log) for
details.
Common problems, Check:
- Path given for cuiConfigFile environment variable
- File paths in cuiconfig.xml
Otherwise, congratulations! You now have now installed the CUI!
This should be accessible via: http://yourhost:your/
port/MyCUIInstallation.
However, you will now need to create users for the CUI before you
can access it. To do this we use the CommonAdminSite
(CAI).
The appearance of the CUI can be changed in many ways.
For simple cosmetic changes (e.g. colours, fonts) the CSS file
webapps/cui/cui.css may be modified.
For more advanced changes, the XSLT templates themselves can be
modified. These are found in
webapps/cui/WEB-INF/templates
In this folder, the XSLT (web page generation) templates for each
language are defined. A special folder called main
contains the full versions of each file. Normally each file in the
specific language folders simply import whatever is in the "main"
folder. This gives the customiser two options:
(a) modify the file to be changed in main. This will be a global
change affecting all templates that reference it.
(b) modifiy the file to be changed inside a local language
folder, e.g. you can modify FR/Login.xslt and this will
only change the French login screen.
- NOTE: Each language folder has a single
lang.xslt file which contains the majority of the
display strings used by the CUI (some special ones are in XML table
code files). CUI operators are free to change these to their local
requirements.
The templates folder of the CommonUserInterface
distribution (or inside the cui.war file depending on
how the CommonUserInterface
is run) contains the pages displayed by the CUI.
By default, there are four folders in the standard distribution
of the templates folder. These are main,
EN, FR and ZZ.
The main folder contains the master (full) templates
for each page in the system. The EN, FR
and ZZ folders contain files whose names match those in
the main folder but if you inspect the files in these
folders you will find they are very short, typically they only
consist of a few lines, all they do is to "include" the content of
the file located in the main folder.
The EN and FR folders store the English
and French versions of the main templates. The ZZ
folder is a special "system" folder, it is the language used when
"System" is selected from the drop-down language menu on the CUI, it
is intended for developer use only and should be disabled prior to
production.
Each language folder contains one special file named
lang.xslt. This contains the majority of the strings /
labels used in the CUI (no language information is hard-coded into
the normal templates, they all import the lang.xslt
file, meaning there is only one XSLT file to translate for each
langauge.)
So, to create a new translation for the CUI, one must follow
these steps.
a) copy the EN folder to the language code for the
new language, e.g. for Germany, DE
b) translate each label in the file lang.xslt in the
DE folder
c) some labels in the CUI are not to be found in the
lang.xslt file as they are stored in the normal TableCode
format. They are found in the DataLayer
folder tables folder of CUI. If a suitable
default.xml for your language is not present, a new
translated default.xml must be created in a appropriate
language / dialect subfolder, e.g. DE/DEU (same system as for normal
EBR tables). Labels stored in TableCode
format include the EbrNode
names, form labels and form errors.
d) Translate the file default.xml located in
xxx_NG_yy/tables/1/DEF/EN/EBR/ and add it to the subfolder
xxx_NG_yy/tables/1/TRA/language/dialect e.g.
ITA_NG_ic/tables/1/TRA/IT/ITA/default.xml for the italian
translation.
e) Translate the file default.xml located in
EBR/tables/DEF/EN/ENR/ and add it to the subfolder
EBR/tables/1/TRA/language/dialect e.g.
EBR/tables/DEF/IT/ITA/default.xml
f) configure the CUI to offer the new language. This is done by
modifying the cuiconfig.xml file. See the file for
details.
| 
Edit menu 
